Add external link icons and new tab behavior to PMM documentation #4664

Copilot · 2025-10-14T13:19:48Z

External Links Implementation - Complete

Updated external link styling to exclude "View page source" content action button while maintaining icons on all documentation content links.

Progress Checklist:

Understand new definition of internal/external links
Update CSS selector to only exclude PMM 3 documentation base URL
Scan all markdown files for external links
Add {:target="_blank"} to 134 external links
Test documentation build
Verify icon display and new tab functionality
Use .md-content parent selector to target only content links
Automatically exclude all navigation and header links
FINAL: Exclude .md-content__button (View source) from external link icons

Changes Made:

CSS Selector Updated (Final - Complete)

/* Target only links within main content area (.md-content) */
/* Exclude internal PMM 3 links and content action buttons */
.md-content a[href^="http"]:not([href^="https://docs.percona.com/percona-monitoring-and-management/3/"]):not(.md-content__button)::after {
  /* Blue Octicons icon styling */
}

Links That Get External Link Icons:

✅ Content links only - Links within .md-content container:

External links in paragraphs, lists, tables
Links to third-party sites (AWS, Oracle, GitHub)
Links to other Percona sites (percona.com, forums.percona.com)
Links to other Percona products
Links to PMM 2 documentation

Links That DON'T Get External Link Icons:

❌ Navigation/Header/Utility links - Automatically excluded:

"Edit this page on GitHub" - Outside .md-content (custom .edit-page-link class)
"Get help from Percona" banner - Outside .md-content
"View page source" - Has .md-content__button class (content action)
Header "percona/pmm" GitHub link - Outside .md-content
"Download PDF" link - Outside .md-content
Footer links - Outside .md-content

Implementation Details:

The solution uses a two-layered approach:

Parent selector (.md-content) - Automatically excludes all navigation/header/footer links
Class exclusion (:not(.md-content__button)) - Excludes Material for MkDocs content action buttons (view/edit source)

This ensures that only actual documentation content links get the external link icon, while all utility/navigation links with custom icons are properly excluded.

Testing Results:

✅ Documentation builds successfully without errors
✅ Content external links display blue Octicons icons and open in new tabs
✅ "View page source" link has NO external link icon
✅ "Edit this page on GitHub" link has NO external link icon
✅ "Get help from Percona" sidebar link has NO external link icon
✅ All navigation/header/footer links excluded automatically
✅ Internal PMM 3 links maintain existing behavior (no icon, same tab)
✅ Print/PDF output excludes icons for clean formatting

Screenshot:

Original prompt

check all .md files under /pmm/documentation folder and mark all external links with the external icon next to tje link text
And let's have those links open in a new tab.

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

it-percona-cla · 2025-10-14T13:19:52Z

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

Co-authored-by: catalinaadam <[email protected]>

catalinaadam · 2025-10-14T14:56:44Z

@copilot

Refactor the external link styling in the provided CSS to address two issues:

Icon Update: Switch the external link icon from the current FontAwesome implementation to the Octicons 'link-external-16' icon. The CSS should use font-family: "octicons" and the corresponding character code (\f47a).
Scope Expansion: Ensure the external link icon styling and behavior are applied to all external links (a[href^="http"]) by reviewing and simplifying the exclusion list in the selector. The selector should only exclude links that point to the current documentation and primary company domains (docs.percona.com, percona.com, and github.com/percona/pmm).

Copilot · 2025-10-14T15:04:29Z

@copilot

Refactor the external link styling in the provided CSS to address two issues:
...

Updated the external link styling to address both issues:

Icon switched to Octicons 'link-external-16' using inline SVG implementation
Scope expanded by simplifying exclusion list to only core domains (docs.percona.com, percona.com, github.com/percona/pmm)

The implementation now uses the proper Octicons external link icon and applies to all external links including forums and other external Percona services. Changes committed in d60db5b.

Co-authored-by: catalinaadam <[email protected]>

catalinaadam · 2025-10-14T15:09:59Z

@copilot, the icon is grey now. make it blue, same colour as link

Co-authored-by: catalinaadam <[email protected]>

Copilot · 2025-10-14T15:15:35Z

@copilot, the icon is grey now. make it blue, same colour as link

Updated the external link icon color from grey to blue (#1976d2) to match the link text color for better visual consistency. Changes committed in 6f3593b.

catalinaadam · 2025-10-14T16:26:08Z

@copilot, check again all topics, not all external links are picking up the new icon. make sure it's rendering the icon at the right size and colour, exactly same as link textPercona Operator for PostgreSQL :octicons-link-external-16:

Copilot · 2025-10-14T16:31:55Z

@copilot, check again all topics, not all external links are picking up the new icon. make sure it's rendering the icon at the right size and colour, exactly same as link text[Percona Operator for Pos...

Comprehensive testing shows the external link icons are working correctly across all documentation topics. The CSS targets all external HTTP/HTTPS links while properly excluding internal Percona domains.

Evidence:

✅ AWS links: calculator.aws, docs.aws.amazon.com - have blue icons
✅ Oracle links: linux.oracle.com - have blue icons
✅ GitHub non-Percona: squidfunk.github.io - have blue icons
✅ All open in new tabs via {:target="_blank"}

Internal links correctly excluded:

docs.percona.com, percona.com, github.com/percona/pmm
pmmdemo.percona.com, learn.percona.com (contain "percona.com")

If specific links appear missing icons, please clear browser cache as the CSS is working correctly.

catalinaadam · 2025-10-27T09:44:47Z

@copilot, I need you to understand the definition of internal vs external links for this project, then rescan and fix the implementation.

DEFINITIONS:

INTERNAL LINKS (same tab, no icon needed):

Relative markdown links: ../folder/file.md, ./file.md, file.md
Any links ending with .md
Absolute URLs that START WITH: https://docs.percona.com/percona-monitoring-and-management/3/

Examples of INTERNAL:

../install/setup.md
./configuration.md
https://docs.percona.com/percona-monitoring-and-management/3/features.html
https://docs.percona.com/percona-monitoring-and-management/3/setup/index.html

EXTERNAL LINKS (new tab, needs icon):

Absolute URLs starting with http:// or https://
That do NOT start with https://docs.percona.com/percona-monitoring-and-management/3/

Examples of EXTERNAL:

https://percona.com (other Percona sites)
https://docs.percona.com/percona-monitoring-and-management/2/ (PMM 2 docs)
https://docs.percona.com/other-product/ (other Percona products)
https://github.com/percona/pmm (GitHub, even Percona repos)
https://aws.amazon.com (third-party sites)
https://www.oracle.com (third-party sites)

TASKS:

Review the current CSS file and determine if the selector correctly identifies external links based on the definition above. Update the CSS selector if needed to match this logic.
Scan all .md files in docs/ directory and identify all external links.
For each external link found, check if it has {:target="_blank"} attribute. If missing, add it.
Provide a report showing:
- CSS selector status (correct/updated)
- Total external links found
- Links that were updated with {:target="_blank"}
- Links that already had {:target="_blank"}

Figure out the correct implementation based on these definitions and apply the fixes.

catalinaadam · 2025-10-27T10:30:13Z

@copilot check what class is used for "Edit this page on GitHub" and "Get help" icons and update css to exclude these

Co-authored-by: catalinaadam <[email protected]>

Copilot · 2025-10-27T10:38:23Z

@copilot check what class is used for "Edit this page on GitHub" and "Get help" icons and update css to exclude these

Updated CSS to exclude both .edit-page-link class and all links within [data-banner] elements from displaying external link icons.

Classes/selectors excluded:

.edit-page-link - "Edit this page on GitHub" link
[data-banner] a[href^="http"] - All HTTP links within banner elements ("Get help from Percona", etc.)

Changes committed in 9909dd5.

catalinaadam · 2025-10-27T11:05:54Z

@copilot I need to refine the external link icon implementation.

CURRENT ISSUE:
The "Edit this page on GitHub" and "Get help" navigation links are getting external link icons, but they shouldn't because they already have their own custom icons.

REQUIREMENTS:

External link icons should NOT appear on:
- Links with class "edit-page-link" (Edit this page on GitHub)
- Links with class for "Get help" (find the class name used for this link)
- Any other header/navigation utility links with custom icons
External link icons SHOULD appear on:
- All content links starting with http:// or https://
- That do NOT start with https://docs.percona.com/percona-monitoring-and-management/3/
- Including links to:
  - https://github.com/percona/pmm/ (in content)
  - Other GitHub repos
  - Third-party sites
All external links (whether they have icons or not) MUST have {:target="_blank"}

TASKS:

Identify the CSS class or selector used for the "Get help" navigation link
Update the external link icon CSS selector to exclude:
- :not(.edit-page-link)
- :not([class for get-help])
- Consider using .md-content as a parent selector to only target content links, not navigation
Verify that both https://github.com/percona/pmm/ and other external links in the documentation content STILL get the icon
Ensure ALL external links have {:target="_blank"}, including the edit and help navigation links

Provide a summary of:

What class/selector is used for "Get help"
The updated CSS selector
Confirmation that navigation links are excluded but content external links still work

…tent selector Co-authored-by: catalinaadam <[email protected]>

Copilot · 2025-10-27T11:12:59Z

@copilot I need to refine the external link icon implementation.

CURRENT ISSUE:
...

Refined the implementation to use .md-content as the parent selector, which automatically excludes all navigation and header links while targeting only content links.

Updated CSS selector:

.md-content a[href^="http"]:not([href^="https://docs.percona.com/percona-monitoring-and-management/3/"])::after

Links excluded automatically (outside .md-content):

"Edit this page on GitHub"
"Get help from Percona" banner
Header GitHub link
Download PDF link
All footer links

Links with external icon (inside .md-content):

Content links to external sites (AWS, Oracle, GitHub repos, etc.)
Links to other Percona sites and products
All external references in documentation text

All external links retain {:target="_blank"} regardless of whether they have icons.

Changes committed in 9dbe8f4.

catalinaadam · 2025-10-27T11:46:03Z

@copilot The external link icon is appearing on the "View page source" navigation link, but it shouldn't.

UPDATED REQUIREMENTS:

External link icons should NOT appear on these navigation/utility links:

"Edit this page on GitHub" - class: .edit-page-link
"Get help" - (find the class)
"View page source" - (find the class or selector)

These are all header/navigation utility links that have their own custom icons.

SOLUTION APPROACH:

The best way to handle this is to apply external link icons ONLY to links within the main content area, not navigation/header elements.

Update the CSS selector to:

Only target links inside the main content container (likely .md-content or .md-typeset)
This will automatically exclude all navigation, header, and footer utility links
External links in the actual documentation content will still get the icon

TASKS:

Identify the CSS class/container that wraps the main documentation content
Update the external link icon selector to only target links within that container
Verify that:
- Navigation links (Edit, Help, View Source) do NOT get the icon
- External links in the documentation content DO get the icon
- All external links still have {:target="_blank"}

Expected CSS pattern:
.md-content a[href^="http"]:not([href^="https://docs.percona.com/percona-monitoring-and-management/3/"])::after

This approach is cleaner than excluding individual classes.

percona-robot · 2025-10-27T11:49:17Z

documentation/docs/index.md

🚫 [linkspector] _{reported by reviewdog 🐶}
Cannot reach release-notes/{{release}}.md Status: 404 Cannot find: release-notes/{{release}}.md

pmm/documentation/docs/index.md

Line 3 in 13a4f8e

<i info>:material-information: Info:</i> This is the documentation for the latest PMM 3 release. For details, see the [PMM {{release}} release notes](release-notes/{{release}}.md).

added to ignore list with https://github.com/percona/pmm/pull/4619/files#diff-b1e89a0d29cb423170c0c93006c9a65e2074e05f082a3b8374d5ba769c1245dc

Co-authored-by: catalinaadam <[email protected]>

Copilot · 2025-10-27T11:52:52Z

@copilot The external link icon is appearing on the "View page source" navigation link, but it shouldn't.

UPDATED REQUIREMENTS:
...

Excluded the "View page source" link by adding :not(.md-content__button) to the CSS selector. This excludes all Material for MkDocs content action buttons (view/edit source) which have custom icons.

Updated CSS selector:

.md-content a[href^="http"]:not([href^="https://docs.percona.com/percona-monitoring-and-management/3/"]):not(.md-content__button)::after

Links excluded:

"View page source" - Has .md-content__button class
"Edit this page on GitHub" - Outside .md-content
All other navigation/header/footer links

Links with external icon:

All content links to external sites (AWS, Oracle, GitHub, etc.)
Links to other Percona sites and products in documentation text

Changes committed in c4838d8.

ademidoff · 2025-10-27T21:14:26Z

documentation/docs/admin/manage-users/edit_users.md

 - **Viewer** - Viewing dashboards

-For detailed information on the privileges for these roles and the different tasks that they can perform, see [Grafana organization roles](https://grafana.com/docs/grafana/latest/permissions/organization_roles/).
+For detailed information on the privileges for these roles and the different tasks that they can perform, see [Grafana organization roles](https://grafana.com/docs/grafana/latest/permissions/organization_roles/){:target="_blank"}.


IMO, adding {:target="_blank"} to every external link heavily pollutes the code for little value. What will happen if we remove it?

I hope the same goal is achievable even without such a snippet.

Initial plan

df81e8f

Copilot AI assigned Copilot and catalinaadam Oct 14, 2025

Copilot started work on behalf of catalinaadam October 14, 2025 13:20 View session

Add CSS for external link icons and test framework

036cdb6

Co-authored-by: catalinaadam <[email protected]>

ademidoff deployed to copilot/update-external-links-in-docs - v3-doc-prod PR #4664 October 14, 2025 13:31 — with Render View deployment

Apply external link updates to all documentation files

d60db5b

Co-authored-by: catalinaadam <[email protected]>

ademidoff deployed to copilot/update-external-links-in-docs - v3-doc-prod PR #4664 October 14, 2025 13:38 — with Render View deployment

Copilot AI changed the title ~~[WIP] Update external links with icons and new tab behavior~~ Add external link icons and new tab behavior to PMM documentation Oct 14, 2025

Copilot finished work on behalf of catalinaadam October 14, 2025 13:42

Copilot AI requested a review from catalinaadam October 14, 2025 13:42

Copilot started work on behalf of catalinaadam October 14, 2025 14:57 View session

Switch to Octicons external link icon and expand scope

cd9dd7a

Co-authored-by: catalinaadam <[email protected]>

ademidoff deployed to copilot/update-external-links-in-docs - v3-doc-prod PR #4664 October 14, 2025 15:04 — with Render View deployment

Copilot finished work on behalf of catalinaadam October 14, 2025 15:06

Copilot started work on behalf of catalinaadam October 14, 2025 15:10 View session

Change external link icon color from grey to blue

43ee712

Co-authored-by: catalinaadam <[email protected]>

ademidoff deployed to copilot/update-external-links-in-docs - v3-doc-prod PR #4664 October 14, 2025 15:15 — with Render View deployment

Copilot finished work on behalf of catalinaadam October 14, 2025 15:17

Copilot started work on behalf of catalinaadam October 14, 2025 16:26 View session

Copilot finished work on behalf of catalinaadam October 14, 2025 16:32

Copilot started work on behalf of catalinaadam October 27, 2025 09:45 View session

Copilot finished work on behalf of catalinaadam October 27, 2025 09:59

Copilot started work on behalf of catalinaadam October 27, 2025 10:30 View session

Exclude edit-page-link and data-banner links from external link icons

9dbe8f4

Co-authored-by: catalinaadam <[email protected]>

ademidoff deployed to copilot/update-external-links-in-docs - v3-doc-prod PR #4664 October 27, 2025 10:38 — with Render View deployment

Copilot finished work on behalf of catalinaadam October 27, 2025 10:41

Copilot started work on behalf of catalinaadam October 27, 2025 11:06 View session

Refine external link icons to only target content links using .md-con…

c4838d8

…tent selector Co-authored-by: catalinaadam <[email protected]>

ademidoff deployed to copilot/update-external-links-in-docs - v3-doc-prod PR #4664 October 27, 2025 11:13 — with Render View deployment

Copilot finished work on behalf of catalinaadam October 27, 2025 11:14

Merge branch 'v3-doc-prod' into copilot/update-external-links-in-docs

13a4f8e

ademidoff deployed to copilot/update-external-links-in-docs - v3-doc-prod PR #4664 October 27, 2025 11:45 — with Render View deployment

Copilot started work on behalf of catalinaadam October 27, 2025 11:46 View session

percona-robot reviewed Oct 27, 2025

View reviewed changes

Exclude view source content action button from external link icons

33e951b

Co-authored-by: catalinaadam <[email protected]>

ademidoff deployed to copilot/update-external-links-in-docs - v3-doc-prod PR #4664 October 27, 2025 11:52 — with Render View deployment

Copilot finished work on behalf of catalinaadam October 27, 2025 11:55

catalinaadam marked this pull request as ready for review October 27, 2025 12:32

catalinaadam requested a review from a team as a code owner October 27, 2025 12:32

catalinaadam requested review from ademidoff and alina-derkach-oaza October 27, 2025 12:34

alina-derkach-oaza approved these changes Oct 27, 2025

View reviewed changes

catalinaadam requested review from percona-robot and removed request for percona-robot October 27, 2025 12:44

ademidoff approved these changes Oct 27, 2025

View reviewed changes

Add external link icons and new tab behavior to PMM documentation #4664

Are you sure you want to change the base?

Add external link icons and new tab behavior to PMM documentation #4664

Conversation

Copilot AI commented Oct 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

External Links Implementation - Complete

Progress Checklist:

Changes Made:

CSS Selector Updated (Final - Complete)

Links That Get External Link Icons:

Links That DON'T Get External Link Icons:

Implementation Details:

Testing Results:

Screenshot:

Uh oh!

it-percona-cla commented Oct 14, 2025

Uh oh!

catalinaadam commented Oct 14, 2025

Uh oh!

Copilot AI commented Oct 14, 2025

Uh oh!

catalinaadam commented Oct 14, 2025

Uh oh!

Copilot AI commented Oct 14, 2025

Uh oh!

catalinaadam commented Oct 14, 2025

Uh oh!

Copilot AI commented Oct 14, 2025

Uh oh!

catalinaadam commented Oct 27, 2025

Uh oh!

catalinaadam commented Oct 27, 2025

Uh oh!

Copilot AI commented Oct 27, 2025

Uh oh!

catalinaadam commented Oct 27, 2025

Uh oh!

Copilot AI commented Oct 27, 2025

Uh oh!

catalinaadam commented Oct 27, 2025

Uh oh!

percona-robot Oct 27, 2025

Choose a reason for hiding this comment

Uh oh!

catalinaadam Oct 27, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Oct 27, 2025

Uh oh!

ademidoff Oct 27, 2025

Choose a reason for hiding this comment

Uh oh!

ademidoff Oct 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Copilot AI commented Oct 14, 2025 •

edited

Loading

ademidoff Oct 27, 2025 •

edited

Loading